---
title: "Popover"
description: "Popover is a non-modal dialog that floats around its disclosure. It's commonly used for displaying additional rich content on top of something."
---

import {popoverContent} from "@/content/components/popover";

# Popover

Popover is a **non-modal** dialog that floats around its disclosure. It's commonly used for displaying
additional rich content on top of something.

<ComponentLinks component="popover" reactAriaHook="usePopover" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add popover",
    npm: "npm install @heroui/popover",
    yarn: "yarn add @heroui/popover",
    pnpm: "pnpm add @heroui/popover",
    bun: "bun add @heroui/popover"
  }}
/>

## Import

HeroUI exports 3 popover-related components:

- **Popover**: The main component to display a popover.
- **PopoverTrigger**: The component that triggers the popover.
- **PopoverContent**: The component that contains the popover content.

<ImportTabs
  commands={{
    main: 'import {Popover, PopoverTrigger, PopoverContent} from "@heroui/react";',
    individual: 'import {Popover, PopoverTrigger, PopoverContent} from "@heroui/popover";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={popoverContent.usage} />

### With Arrow

<CodeDemo title="With Arrow" files={popoverContent.arrow} />

### Colors

<CodeDemo title="Colors" files={popoverContent.colors} />

### Placements

<CodeDemo title="Placements" files={popoverContent.placements} />

### Offset

<CodeDemo title="Offset" files={popoverContent.offset} />

### Controlled

<CodeDemo title="Controlled" files={popoverContent.controlled} />

### Title Props

To be sure that the popover exposes the correct title to assistive technologies, you should use the
`titleProps` prop on the `PopoverContent` component. To use this prop, you must pass a function as a child.

<CodeDemo title="Title Props" files={popoverContent.titleProps} />

### With Form

The `Popover` handles the focus within the popover content. It means that you can use the popover with
form elements without any problem. the focus returns to the trigger when the popover closes.

<CodeDemo title="With Form" files={popoverContent.withForm} />

> **Note**: You can add the `autoFocus` prop to the first `Input` component to focus it when the popover opens.

### Backdrop

The `Popover` component has a `backdrop` prop to show a backdrop behind the popover. The backdrop can be
either `transparent`, `opaque` or `blur`. The default value is `transparent`.

<CodeDemo title="Backdrop" files={popoverContent.backdrop} />

### Custom Motion

Popover offers a `motionProps` property to customize the `enter` / `exit` animation.

<CodeDemo title="Custom Motion" files={popoverContent.customMotion} />

> Learn more about Framer motion variants [here](https://www.framer.com/motion/animation/#variants).

### Custom Trigger

<CodeDemo title="Custom Trigger" files={popoverContent.customTrigger} />

## Slots

- **base**: The main popover slot, it wraps the popover content and contains the arrow as a pseudo-element (::before).
- **trigger**: The popover trigger slot, it has small styles to ensure the trigger works correctly.
- **backdrop**: The backdrop slot, it contains the backdrop styles.
- **content**: The content slot, it contains the popover content.

### Custom Styles

You can customize the `Popover` component by passing custom Tailwind CSS classes to the component slots.

<CodeDemo title="Custom Styles" files={popoverContent.customStyles} />

<Spacer y={4} />

## Data Attributes

`Popover` has the following attributes on the `PopoverContent` element:

- **data-open**:
  When the popover is open. Based on popover state.
- **data-placement**:
  The placement of the popover. Based on `placement` prop. The arrow element is positioned based on this attribute.
- **data-focus**:
  When the popover is being focused. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).
- **data-focus-visible**:
  When the popover is being focused with the keyboard. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).

<Spacer y={4} />

## Accessibility

- The trigger and popover are automatically associated semantically via ARIA.
- Content outside the popover is hidden from assistive technologies while it is open.
- The popover closes when interacting outside, or pressing the <Kbd>Escape</Kbd> key.
- Focus is moved into the popover on mount, and restored to the trigger element on unmount.
- The popover is positioned relative to the trigger element, and automatically flips and adjusts to avoid overlapping with the edge of the browser window.
- Scrolling is prevented outside the popover to avoid unintentionally repositioning or closing it.

<Spacer y={4} />

## API

### Popover Props

<APITable
  data={[
    {
      attribute: "children*",
      type: "ReactNode[]",
      description: "The content of the popover. It's usually the PopoverTrigger and PopoverContent.",
      default: "-"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The popover content font size.",
      default: "md"
    },
    {
      attribute: "color",
      type: "default | primary | secondary | success | warning | danger",
      description: "The popover color theme.",
      default: "default"
    },
    {
      attribute: "radius",
      type: "none | sm | md | lg | full",
      description: "The popover border radius.",
      default: "lg"
    },
    {
      attribute: "shadow",
      type: "none | sm | md | lg",
      description: "The popover shadow.",
      default: "lg"
    },
    {
      attribute: "backdrop",
      type: "transparent | opaque | blur",
      description: "The popover backdrop type.",
      default: "transparent"
    },
    {
      attribute: "placement",
      type: "PopoverPlacement",
      description: "The placement of the popover relative to its trigger reference.",
      default: "bottom"
    },
    {
      attribute: "state",
      type: "OverlayTriggerState",
      description: "The controlled state of the popover.",
      default: "-"
    },
    {
      attribute: "isOpen",
      type: "boolean",
      description: "Whether the popover is open by default (controlled).",
      default: "-"
    },
    {
      attribute: "defaultOpen",
      type: "boolean",
      description: "Whether the popover is open by default (uncontrolled).",
      default: "-"
    },
    {
      attribute: "offset",
      type: "number",
      description: "The distance or margin between the reference and popper.",
      default: "7"
    },
    {
      attribute: "containerPadding",
      type: "number",
      description: "The placement padding between the element and its surrounding container.",
      default: "12"
    },
    {
      attribute: "crossOffset",
      type: "number",
      description: "The additional offset applied along the cross axis between the element and its anchor element.",
      default: "0"
    },
    {
      attribute: "triggerType",
      type: "dialog | menu | listbox | tree | grid",
      description: "Type of popover that is opened by the trigger.",
      default: "dialog"
    },
    {
      attribute: "showArrow",
      type: "boolean",
      description: "Whether the popover should have an arrow.",
      default: "false"
    },
    {
      attribute: "shouldFlip",
      type: "boolean",
      description: "Whether the popover should change its placement and flip when it's about to overflow.",
      default: "true"
    },
    {
      attribute: "triggerScaleOnOpen",
      type: "boolean",
      description: "Whether the trigger should scale down when the popover is open.",
      default: "true"
    },
    {
      attribute: "shouldBlockScroll",
      type: "boolean",
      description: "Whether the popover should block the scroll outside the popover.",
      default: "false"
    },
    {
      attribute: "shouldCloseOnScroll",
      type: "boolean",
      description: "Whether the popover should close on scroll.",
      default: "true"
    },
    {
      attribute: "isKeyboardDismissDisabled",
      type: "boolean",
      description: "Whether pressing the escape key to close the popover should be disabled.",
      default: "false"
    },
    {
      attribute: "shouldCloseOnBlur",
      type: "boolean",
      description: "Whether the popover should close when focus is lost or moves outside it.",
      default: "false"
    },
    {
      attribute: "motionProps",
      type: "MotionProps",
      description: "The props to modify the framer motion animation.",
      default: "-"
    },
    {
      attribute: "portalContainer",
      type: "HTMLElement",
      description: "The container element in which the overlay portal will be placed.",
      default: "document.body"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether the popover is animated.",
      default: "false"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<'base' | 'trigger' | 'backdrop' | 'content', string>>",
      description: "Allows to set custom class names for the popover slots.",
      default: "-"
    }
  ]}
/>

### Popover Events

<APITable
  data={[
    {
      attribute: "onOpenChange",
      type: "(isOpen: boolean) => void",
      description: "Handler that is called when the popover's open state changes.",
      default: "-"
    },
    {
      attribute: "shouldCloseOnInteractOutside",
      type: "(e: HTMLElement) => void",
      description: "When user interacts with the argument element outside of the popover ref, return true if onClose should be called.",
      default: "-"
    },
    {
      attribute: "onClose",
      type: "() => void",
      description: "Handler that is called when the popover should close.",
      default: "-"
    }
  ]}
/>

### PopoverTrigger Props

<APITable
  data={[
    {
      attribute: "children*",
      type: "ReactNode",
      description: "The popover trigger component, ensure the children passed is focusable.",
      default: "-"
    }
  ]}
/>

### PopoverContent Props

<APITable
  data={[
    {
      attribute: "children",
      type: "ReactNode",
      description: "The content that is displayed when the trigger is pressed.",
      default: "-"
    }
  ]}
/>

### Popover types

<Spacer y={1} />

#### Popover Placement

```ts
type PopoverPlacement =
  | "top"
  | "bottom"
  | "right"
  | "left"
  | "top-start"
  | "top-end"
  | "bottom-start"
  | "bottom-end"
  | "left-start"
  | "left-end"
  | "right-start"
  | "right-end";
```

#### Motion Props

```ts
export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/
```
